'\" te
.\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH NEWPAD 3XCURSES "Jun 5, 2002"
.SH NAME
newpad, pnoutrefresh, prefresh, subpad \- create or refresh a pad or subpad
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
\fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]

\fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]

#include <curses.h>

\fBWINDOW *\fR\fBnewpad\fR(\fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR);
.fi

.LP
.nf
\fBint\fR \fBpnoutrefresh\fR(\fBWINDOW *\fR\fIpad\fR, \fBint\fR \fIpminrow\fR, \fBint\fR \fIpmincol\fR, \fBint\fR \fIsminrow\fR,
     \fBint\fR \fIsmincol\fR,\fBint\fR \fIsmaxrow\fR, \fBint\fR \fIsmaxcol\fR);
.fi

.LP
.nf
\fBint\fR \fBprefresh\fR(\fBWINDOW *\fR\fIpad\fR, \fBint\fR \fIpminrow\fR, \fBint\fR \fIpmincol\fR, \fBint\fR \fIsminrow\fR,
     \fBint\fR \fIsmincol\fR,\fBint\fR \fIsmaxrow\fR, \fBint\fR \fIsmaxcol\fR);
.fi

.LP
.nf
\fBWINDOW *\fR\fBsubpad\fR(\fBWINDOW *\fR\fIorig\fR, \fBint\fR \fInlines\fR, \fBint\fR \fIncols\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fInlines\fR\fR
.ad
.RS 11n
Is the number of lines in the pad to be created.
.RE

.sp
.ne 2
.na
\fB\fIncols\fR\fR
.ad
.RS 11n
Is the number of columns in the pad to be created.
.RE

.sp
.ne 2
.na
\fB\fIpad\fR\fR
.ad
.RS 11n
Is a pointer to the pad to refresh.
.RE

.sp
.ne 2
.na
\fB\fIpminrow\fR\fR
.ad
.RS 11n
Is the row coordinate of the upper left corner of the pad rectangle to be
copied
.RE

.sp
.ne 2
.na
\fB\fIpmincol\fR\fR
.ad
.RS 11n
Is the column coordinate of the upper left corner of the pad rectangle to be
copied.
.RE

.sp
.ne 2
.na
\fB\fIsminrow\fR\fR
.ad
.RS 11n
Is the row coordinate of the upper left corner of the rectangle on the physical
screen where pad is to be positioned.
.RE

.sp
.ne 2
.na
\fB\fIsmincol\fR\fR
.ad
.RS 11n
Is the column coordinate of the upper left corner of the rectangle on the
physical screen where pad is to be positioned.
.RE

.sp
.ne 2
.na
\fB\fIsmaxrow\fR\fR
.ad
.RS 11n
Is the row coordinate of the lower right corner of the rectangle on the
physical screen where the pad is to be positioned.
.RE

.sp
.ne 2
.na
\fB\fIsmaxcol\fR\fR
.ad
.RS 11n
Is the column coordinate of the lower right corner of the rectangle on the
physical screen where the pad is to be positioned.
.RE

.sp
.ne 2
.na
\fB\fIorig\fR\fR
.ad
.RS 11n
Is a pointer to the parent pad within which a sub-pad is created.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBnewpad()\fR function creates a new pad with the specified number of
lines and columns.  A pointer to the new pad structure is returned.  A pad
differs from a window in that it is not restricted to the size of the  physical
screen.  It is useful when only part of a large window will be displayed at any
one  time.
.sp
.LP
Automatic refreshes by scrolling or echoing of input do not take place when
pads are used.  Pads have their own refresh commands, \fBprefresh()\fR and
\fBpnoutrefresh()\fR.
.sp
.LP
The \fBprefresh()\fR function copies the specified portion of the logical pad
to the terminal screen.  The parameters \fIpmincol\fR and \fIpminrow\fR specify
the upper left corner of the rectangular area of the pad to be displayed. The
lower right coordinate of the rectangular area of the pad that is to be
displayed is calculated from the screen parameters (\fIsminrow\fR,
\fIsmincol\fR, \fIsmaxrow\fR, \fIsmaxcol\fR).
.sp
.LP
This function calls the \fBpnoutrefresh()\fR function to copy the specified
portion of \fIpad\fR to the terminal screen and the \fBdoupdate\fR(3XCURSES)
function to do the actual update.  The logical cursor is copied to the same
location in the physical window unless \fBleaveok\fR(3XCURSES) is enabled (in
which case, the cursor is placed in a position that the program finds
convenient).
.sp
.LP
When outputting several pads at once, it is often more efficient to call the
\fBpnoutrefresh()\fR and \fBdoupdate()\fR functions directly. A call to
\fBpnoutrefresh()\fR for each pad first, followed by only one call  to
\fBdoupdate()\fR to update the screen, results in one burst of output,  fewer
characters sent, and less CPU time used.
.sp
.LP
The \fBsubpad()\fR function creates a sub-pad within the pad \fIorig\fR with
the specified number of lines and columns.  A pointer to the new pad structure
is returned. The sub-pad is positioned in the middle of \fIorig\fR.  Any
changes made to one pad affect the other.   \fBtouchwin\fR(3XCURSES) or
\fBtouchline\fR(3XCURSES) will likely have to be called on pad  \fIorig\fR to
correctly update the window.
.SH RETURN VALUES
.sp
.LP
On success, the \fBnewpad()\fR and \fBsubpad()\fR functions returns a pointer
to the new pad data structure. Otherwise, they return a null pointer.
.sp
.LP
On success, the \fBpnoutrefresh()\fR and \fBprefresh()\fR functions return
\fBOK\fR. Otherwise, they return \fBERR\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
.BR clearok (3XCURSES),
.BR doupdate (3XCURSES),
.BR is_linetouched (3XCURSES),
.BR libcurses (3XCURSES),
.BR pechochar (3XCURSES),
.BR attributes (7),
.BR standards (7)
